Skip to content

Comments

Add URI query docs#88

Merged
adam-fowler merged 5 commits intomainfrom
query-docs
Mar 19, 2025
Merged

Add URI query docs#88
adam-fowler merged 5 commits intomainfrom
query-docs

Conversation

@adam-fowler
Copy link
Member

We didn't have any docs on URL query parsing

@JoachimM7
Copy link
Contributor

I would recommend to add an explanation, what Query parameters are. So in the examples I would add:

router.get("/user") { request, context in
    // access the query parameter ?id=...
    let id = request.uri.queryParameters.get("id", as: Int.self) else { throw HTTPError(.badRequest) }
    return getUser(id: id)
}

and

...
router.get("tile") { request, context in
    // access the query parameters ?x=...&y=...
    let position = request.uri.decodeQuery(as: Coordinate.self, context: context)
    return tiles.get(at: position)
}

Also I would suggest to add the sentence:

If you don't need all parameters, mark the properties in the struct as Optional.

Maybe you also can add:

The parameters will automatically be percent encoded

@adam-fowler
Copy link
Member Author

@JoachimM7 I've added code comments about URL query format and a bit of text about percent decoding.

I'm not certain about the optional bit as this is kinda assumed knowledge when using Codable. I'm not generating general purpose swift documentation. Also the text isn't totally correct. In a way the text should be. If the existence of a query parameter is optional then they should be marked as Optional in the type you are decoding to. ie if is optional then mark it as optional.

@adam-fowler adam-fowler requested a review from Joannis March 18, 2025 16:46
@adam-fowler adam-fowler merged commit ece641d into main Mar 19, 2025
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants